Move documentation to inline comments: GtkLabel

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 5417f735f0f93d0873b599ea65ed7f5bedb4d23b..0c37085575ebd333381c257ec514aa7b78ab05d7 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -61,6 +61,7 @@ gtkimcontextsimple.sgml
 gtkimmulticontext.sgml
 gtkinvisible.sgml
 gtkitemfactory.sgml
+gtklabel.sgml
 gtklayout.sgml
 gtklinkbutton.sgml
 gtkliststore.sgml

diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml
deleted file mode 100644 (file)
index 0740e5f..0000000
--- a/docs/reference/gtk/tmpl/gtklabel.sgml
+++ /dev/null
@@ -1,751 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkLabel
-
-<!-- ##### SECTION Short_Description ##### -->
-A widget that displays a small to medium amount of text
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkLabel widget displays a small amount of text. As the name
-implies, most labels are used to label another widget such as a
-#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
-</para>
-
-<refsect2 id="GtkLabel-BUILDER-UI">
-<title>GtkLabel as GtkBuildable</title>
-<para>
-The GtkLabel implementation of the GtkBuildable interface supports a 
-custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
-elements. the &lt;attribute&gt; element has attributes named name, value,
-start and end and allows you to specify #PangoAttribute values for this label.
-</para>
-<example>
-<title>A UI definition fragment specifying Pango attributes</title>
-<programlisting><![CDATA[
-<object class="GtkLabel">
-  <attributes>
-    <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
-    <attribute name="background" value="red" start="5" end="10"/>"
-  </attributes>
-</object>
-]]></programlisting>
-</example>
-<para>
-The start and end attributes specify the range of characters to which the
-Pango attribute applies. If start and end are not specified, the attribute is
-applied to the whole text. Note that specifying ranges does not make much
-sense with translatable attributes. Use markup embedded in the translatable
-content instead.
-</para>
-</refsect2>
-
-
-<refsect2>
-<title>Mnemonics</title>
-
-<para>
-Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
-underlined characters in the label, used for keyboard navigation.
-Mnemonics are created by providing a string with an underscore before
-the mnemonic character, such as <literal>"_File"</literal>, to the
-functions gtk_label_new_with_mnemonic() or
-gtk_label_set_text_with_mnemonic().
-</para>
-
-<para>
-Mnemonics automatically activate any activatable widget the label is
-inside, such as a #GtkButton; if the label is not inside the
-mnemonic's target widget, you have to tell the label about the target
-using gtk_label_set_mnemonic_widget(). Here's a simple example where
-the label is inside a button:
-
-<informalexample>
-<programlisting>
-  /* Pressing Alt+H will activate this button */
-  button = gtk_button_new (<!-- -->);
-  label = gtk_label_new_with_mnemonic ("_Hello");
-  gtk_container_add (GTK_CONTAINER (button), label);
-</programlisting>
-</informalexample>
-There's a convenience function to create buttons with a mnemonic label 
-already inside:
-
-<informalexample>
-<programlisting>
-  /* Pressing Alt+H will activate this button */
-  button = gtk_button_new_with_mnemonic ("_Hello");
-</programlisting>
-</informalexample>
-
-To create a mnemonic for a widget alongside the label, such as a 
-#GtkEntry, you have to point the label at the entry with 
-gtk_label_set_mnemonic_widget():
-<informalexample>
-<programlisting>
-  /* Pressing Alt+H will focus the entry */
-  entry = gtk_entry_new (<!-- -->);
-  label = gtk_label_new_with_mnemonic ("_Hello");
-  gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
-</programlisting>
-</informalexample>
-
-</para>
-
-</refsect2>
-
-<refsect2>
-<title>Markup (styled text)</title>
-
-<para>
-To make it easy to format text in a label (changing colors, fonts,
-etc.), label text can be provided in a simple <link
-linkend="PangoMarkupFormat">markup format</link>.
-Here's how to create a label with a small font:
-<informalexample>
-<programlisting>
-  label = gtk_label_new (NULL);
-  gtk_label_set_markup (GTK_LABEL (label), "&lt;small&gt;Small text&lt;/small&gt;");
-</programlisting>
-</informalexample>
-(See <link
-linkend="PangoMarkupFormat">complete documentation</link> of available
-tags in the Pango manual.)
-</para>
-<para>
-The markup passed to gtk_label_set_markup() must be valid; for example,
-literal &lt;/&gt;/&amp; characters must be escaped as &amp;lt;,
-&amp;gt;, and &amp;amp;. If you pass text obtained from the user, file,
-or a network to gtk_label_set_markup(), you'll want to escape it with
-g_markup_escape_text() or g_markup_printf_escaped().
-</para>
-<para>
-Markup strings are just a convenient way to set the #PangoAttrList on
-a label; gtk_label_set_attributes() may be a simpler way to set
-attributes in some cases. Be careful though; #PangoAttrList tends to
-cause internationalization problems, unless you're applying attributes
-to the entire string (i.e. unless you set the range of each attribute
-to [0, G_MAXINT)). The reason is that specifying the start_index and
-end_index for a #PangoAttribute requires knowledge of the exact string
-being displayed, so translations will cause problems.
-</para>
-</refsect2>
-
-<refsect2>
-<title>Selectable labels</title>
-
-<para>
-Labels can be made selectable with gtk_label_set_selectable(). 
-Selectable labels allow the user to copy the label contents to 
-the clipboard. Only labels that contain useful-to-copy information
-&mdash; such as error messages &mdash; should be made selectable.
-</para>
-</refsect2>
-
-<refsect2 id="label-text-layout">
-<title>Text layout</title>
-
-<para>
-A label can contain any number of paragraphs, but will have
-performance problems if it contains more than a small number.
-Paragraphs are separated by newlines or other paragraph separators
-understood by Pango.
-</para>
-<para>
-Labels can automatically wrap text if you call
-gtk_label_set_line_wrap().
-</para>
-<para>
-gtk_label_set_justify() sets how the lines in a label align
-with one another. If you want to set how the label as a whole
-aligns in its available space, see gtk_misc_set_alignment().
-</para>
-<para>
-The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
-can be used to control the size allocation of ellipsized or wrapped
-labels. For ellipsizing labels, if either is specified (and less
-than the actual text size), it is used as the minimum width, and the actual
-text size is used as the natural width of the label. For wrapping labels,
-width-chars is used as the minimum width, if specified, and max-width-chars
-is used as the natural width. Even if max-width-chars specified, wrapping
-labels will be rewrapped to use all of the available width.
-</para>
-<note><para>Note that the interpretation of #GtkLabel:width-chars and
-#GtkLabel:max-width-chars has changed a bit with the introduction of
-width-for-height geometry management and #GtkExtendedLayout.</para></note>
-</refsect2>
-
-<refsect2>
-<title>Links</title>
-
-<para>
-Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
-to regular Pango markup. The markup for links is borrowed from HTML, using the
-<tag>a</tag> with href and title attributes. GTK+ renders links similar to the
-way they appear in web browsers, with colored, underlined text. The title
-attribute is displayed as a tooltip on the link. An example looks like this:
-<informalexample><programlisting>
-gtk_label_set_markup (label, "Go to the &lt;a href=\"http://www.gtk.org\" title=\"&amp;lt;i&amp;gt;Our&amp;/i&amp;gt; website\"&gt;GTK+ website&lt;/a&gt; for more...");
-</programlisting></informalexample>
-It is possible to implement custom handling for links and their tooltips with
-the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
-</para>
-
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkLabel ##### -->
-<para>
-This should not be accessed directly.  Use the accessor functions as
-described below.
-</para>
-
-
-<!-- ##### SIGNAL GtkLabel::activate-current-link ##### -->
-<para>
-
-</para>
-
-@label: the object which received the signal.
-
-<!-- ##### SIGNAL GtkLabel::activate-link ##### -->
-<para>
-
-</para>
-
-@label: the object which received the signal.
-@arg1: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
-<para>
-
-</para>
-
-@label: the object which received the signal.
-
-<!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
-<para>
-
-</para>
-
-@label: the object which received the signal.
-@arg1: 
-@arg2: 
-@arg3: 
-
-<!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
-<para>
-
-</para>
-
-@label: the object which received the signal.
-@arg1: 
-
-<!-- ##### ARG GtkLabel:angle ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:attributes ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:cursor-position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:ellipsize ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:justify ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:max-width-chars ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:pattern ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:selectable ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:selection-bound ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:single-line-mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:track-visited-links ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:use-markup ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:use-underline ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:width-chars ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:wrap ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkLabel:wrap-mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_label_new ##### -->
-<para>
-
-</para>
-
-@str: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_set_text ##### -->
-<para>
-
-</para>
-
-@label: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_label_set_attributes ##### -->
-<para>
-
-</para>
-
-@label: 
-@attrs: 
-
-
-<!-- ##### FUNCTION gtk_label_set_markup ##### -->
-<para>
-
-</para>
-
-@label: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### -->
-<para>
-
-</para>
-
-@label: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_label_set_pattern ##### -->
-<para>
-The pattern of underlines you want under the existing text within the
-#GtkLabel widget.  For example if the current text of the label says
-&quot;FooBarBaz&quot; passing a pattern of &quot;___   ___&quot; will underline
-&quot;Foo&quot; and &quot;Baz&quot; but not &quot;Bar&quot;.
-</para>
-
-@label: The #GtkLabel you want to set the pattern to.
-@pattern: The pattern as described above.
-
-
-<!-- ##### FUNCTION gtk_label_set_justify ##### -->
-<para>
-
-</para>
-
-@label: 
-@jtype: 
-
-
-<!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
-<para>
-
-</para>
-
-@label: 
-@mode: 
-
-
-<!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
-<para>
-
-</para>
-
-@label: 
-@n_chars: 
-
-
-<!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
-<para>
-
-</para>
-
-@label: 
-@n_chars: 
-
-
-<!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
-<para>
-
-</para>
-
-@label: 
-@wrap: 
-
-
-<!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
-<para>
-
-</para>
-
-@label: 
-@wrap_mode: 
-
-
-<!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
-<para>
-
-</para>
-
-@label: 
-@x: 
-@y: 
-
-
-<!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_selectable ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_text ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### -->
-<para>
-
-</para>
-
-@str: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_select_region ##### -->
-<para>
-
-</para>
-
-@label: 
-@start_offset: 
-@end_offset: 
-
-
-<!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### -->
-<para>
-
-</para>
-
-@label: 
-@widget: 
-
-
-<!-- ##### FUNCTION gtk_label_set_selectable ##### -->
-<para>
-
-</para>
-
-@label: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### -->
-<para>
-
-</para>
-
-@label: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_label_get_attributes ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_justify ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_label ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_layout ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
-<para>
-
-</para>
-
-@label: 
-@start: 
-@end: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_get_angle ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_set_label ##### -->
-<para>
-
-</para>
-
-@label: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
-<para>
-
-</para>
-
-@label: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
-<para>
-
-</para>
-
-@label: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
-<para>
-
-</para>
-
-@label: 
-@single_line_mode: 
-
-
-<!-- ##### FUNCTION gtk_label_set_angle ##### -->
-<para>
-
-</para>
-
-@label: 
-@angle: 
-
-
-<!-- ##### FUNCTION gtk_label_get_current_uri ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_label_set_track_visited_links ##### -->
-<para>
-
-</para>
-
-@label: 
-@track_links: 
-
-
-<!-- ##### FUNCTION gtk_label_get_track_visited_links ##### -->
-<para>
-
-</para>
-
-@label: 
-@Returns: 
-
-

diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 04bf4ffb39c8474f8d64b94d82c960d50bd80392..23ae22366f033bae4c61f7abb0e4eb007cfe579a 100644 (file)
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -52,6 +52,184 @@
 #include "gtkprivate.h"
 #include "gtktypebuiltins.h"
 
+
+/**
+ * SECTION:gtklabel
+ * @Short_description: A widget that displays a small to medium amount of text
+ * @Title: GtkLabel
+ *
+ * The #GtkLabel widget displays a small amount of text. As the name
+ * implies, most labels are used to label another widget such as a
+ * #GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
+ *
+ * <refsect2 id="GtkLabel-BUILDER-UI">
+ * <title>GtkLabel as GtkBuildable</title>
+ * <para>
+ * The GtkLabel implementation of the GtkBuildable interface supports a
+ * custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
+ * elements. the &lt;attribute&gt; element has attributes named name, value,
+ * start and end and allows you to specify #PangoAttribute values for this label.
+ *
+ * <example>
+ * <title>A UI definition fragment specifying Pango attributes</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkLabel">
+ *   <attributes>
+ *     <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
+ *     <attribute name="background" value="red" start="5" end="10"/>"
+ *   </attributes>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * The start and end attributes specify the range of characters to which the
+ * Pango attribute applies. If start and end are not specified, the attribute is
+ * applied to the whole text. Note that specifying ranges does not make much
+ * sense with translatable attributes. Use markup embedded in the translatable
+ * content instead.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Mnemonics</title>
+ * <para>
+ * Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
+ * underlined characters in the label, used for keyboard navigation.
+ * Mnemonics are created by providing a string with an underscore before
+ * the mnemonic character, such as <literal>"_File"</literal>, to the
+ * functions gtk_label_new_with_mnemonic() or
+ * gtk_label_set_text_with_mnemonic().
+ *
+ * Mnemonics automatically activate any activatable widget the label is
+ * inside, such as a #GtkButton; if the label is not inside the
+ * mnemonic's target widget, you have to tell the label about the target
+ * using gtk_label_set_mnemonic_widget(). Here's a simple example where
+ * the label is inside a button:
+ *
+ * <informalexample>
+ * <programlisting>
+ *   // Pressing Alt+H will activate this button
+ *   button = gtk_button_new (<!-- -->);
+ *   label = gtk_label_new_with_mnemonic ("_Hello");
+ *   gtk_container_add (GTK_CONTAINER (button), label);
+ * </programlisting>
+ * </informalexample>
+ *
+ * There's a convenience function to create buttons with a mnemonic label
+ * already inside:
+ *
+ * <informalexample>
+ * <programlisting>
+ *   // Pressing Alt+H will activate this button
+ *   button = gtk_button_new_with_mnemonic ("_Hello");
+ * </programlisting>
+ * </informalexample>
+ *
+ * To create a mnemonic for a widget alongside the label, such as a
+ * #GtkEntry, you have to point the label at the entry with
+ * gtk_label_set_mnemonic_widget():
+ *
+ * <informalexample>
+ * <programlisting>
+ *   // Pressing Alt+H will focus the entry
+ *   entry = gtk_entry_new (<!-- -->);
+ *   label = gtk_label_new_with_mnemonic ("_Hello");
+ *   gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
+ * </programlisting>
+ * </informalexample>
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Markup (styled text)</title>
+ * <para>
+ * To make it easy to format text in a label (changing colors, fonts,
+ * etc.), label text can be provided in a simple <link
+ * linkend="PangoMarkupFormat">markup format</link>.
+ * Here's how to create a label with a small font:
+ *
+ * <informalexample>
+ * <programlisting>
+ *   label = gtk_label_new (NULL);
+ *   gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
+ * </programlisting>
+ * </informalexample>
+ *
+ * (See <link
+ * linkend="PangoMarkupFormat">complete documentation</link> of available
+ * tags in the Pango manual.)
+ *
+ * The markup passed to gtk_label_set_markup() must be valid; for example,
+ * literal &lt;, &gt; and &amp; characters must be escaped as \&lt;,
+ * \gt;, and \&amp;. If you pass text obtained from the user, file,
+ * or a network to gtk_label_set_markup(), you'll want to escape it with
+ * g_markup_escape_text() or g_markup_printf_escaped().
+ *
+ * Markup strings are just a convenient way to set the #PangoAttrList on
+ * a label; gtk_label_set_attributes() may be a simpler way to set
+ * attributes in some cases. Be careful though; #PangoAttrList tends to
+ * cause internationalization problems, unless you're applying attributes
+ * to the entire string (i.e. unless you set the range of each attribute
+ * to [0, %G_MAXINT)). The reason is that specifying the start_index and
+ * end_index for a #PangoAttribute requires knowledge of the exact string
+ * being displayed, so translations will cause problems.
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Selectable labels</title>
+ * Labels can be made selectable with gtk_label_set_selectable().
+ * Selectable labels allow the user to copy the label contents to
+ * the clipboard. Only labels that contain useful-to-copy information
+ * &mdash; such as error messages &mdash; should be made selectable.
+ * </refsect2>
+ * <refsect2 id="label-text-layout">
+ * <title>Text layout</title>
+ * <para>
+ * A label can contain any number of paragraphs, but will have
+ * performance problems if it contains more than a small number.
+ * Paragraphs are separated by newlines or other paragraph separators
+ * understood by Pango.
+ *
+ * Labels can automatically wrap text if you call
+ * gtk_label_set_line_wrap().
+ *
+ * gtk_label_set_justify() sets how the lines in a label align
+ * with one another. If you want to set how the label as a whole
+ * aligns in its available space, see gtk_misc_set_alignment().
+ *
+ * The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
+ * can be used to control the size allocation of ellipsized or wrapped
+ * labels. For ellipsizing labels, if either is specified (and less
+ * than the actual text size), it is used as the minimum width, and the actual
+ * text size is used as the natural width of the label. For wrapping labels,
+ * width-chars is used as the minimum width, if specified, and max-width-chars
+ * is used as the natural width. Even if max-width-chars specified, wrapping
+ * labels will be rewrapped to use all of the available width.
+ *
+ * <note><para>
+ * Note that the interpretation of #GtkLabel:width-chars and
+ * #GtkLabel:max-width-chars has changed a bit with the introduction of
+ * <link linkend="geometry-management">width-for-height geometry management.</link>
+ * </para></note>
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Links</title>
+ * <para>
+ * Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
+ * to regular Pango markup. The markup for links is borrowed from HTML, using the
+ * <tag>a</tag> with href and title attributes. GTK+ renders links similar to the
+ * way they appear in web browsers, with colored, underlined text. The title
+ * attribute is displayed as a tooltip on the link. An example looks like this:
+ *
+ * <informalexample><programlisting>
+ * gtk_label_set_markup (label, "Go to the <a href="http://www.gtk.org" title="&lt;i&gt;Our&lt;/i&gt; website">GTK+ website</a> for more...");
+ * </programlisting></informalexample>
+ *
+ * It is possible to implement custom handling for links and their tooltips with
+ * the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
+ * </para>
+ * </refsect2>
+ */
+
+
 /*rint() is only available in GCC and/or C99*/
 #if (__STDC_VERSION__ < 199901L && !defined __GNUC__)
 double rint(double x)
@@ -2632,6 +2810,16 @@ gtk_label_set_pattern_internal (GtkLabel    *label,
   priv->effective_attrs = attrs;
 }
 
+/**
+ * gtk_label_set_pattern:
+ * @label: The #GtkLabel you want to set the pattern to.
+ * @pattern: The pattern as described above.
+ *
+ * The pattern of underlines you want under the existing text within the
+ * #GtkLabel widget.  For example if the current text of the label says
+ * "FooBarBaz" passing a pattern of "___   ___" will underline
+ * "Foo" and "Baz" but not "Bar".
+ */
 void
 gtk_label_set_pattern (GtkLabel           *label,
                       const gchar *pattern)